home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 April: Mac OS SDK / Dev.CD Apr 98 SDK1.toast / Development Kits (Disc 1) / AIAT 1.0.1 / Headers / Storage / IAStorage.h < prev    next >
Encoding:
Text File  |  1997-09-11  |  7.1 KB  |  184 lines  |  [TEXT/CWIE]
  1. // IAStorage.h
  2. //    Copyright:    © 1994 - 1996 by Apple Computer, Inc., all rights reserved.
  3.  
  4.  
  5. // Manages allocation of variable-sized persistent blocks and atomic transactions.
  6.  
  7. #pragma once
  8. #ifndef IAStorage_h
  9. #define IAStorage_h
  10.  
  11. #pragma import on
  12.  
  13. #include "IAStoreStream.h"
  14.  
  15. #pragma IA_BEGIN_EXPORTS
  16.  
  17. typedef uint32            IABlockID;
  18. typedef uint32            IABlockSize;
  19. typedef uint32            IABlockAddress;
  20.  
  21. //    This interface assumes that block IDs are not raw disk addresses, but rather
  22. //    logical block numbers.  This frees clients from having to shadow blocks
  23. //    changed in a transaction, and also enables compaction without knowledge of
  24. //    client data structures.  The downside is that, to be efficient, the 
  25. //    table mapping block-IDs to block-addresses must be memory-resident.
  26. //    So long as most blocks are reasonably large (around 1kb) the memory
  27. //    requirements should not be too bad.
  28.  
  29. class IAStorage : public IAObject {
  30.     friend class IAOutputBlock;
  31.     friend class IAInputBlock;
  32. public:
  33.     // constructor:        notes storeStream & type, creates mutex
  34.                         IAStorage(IAStoreStream* s, uint32 type);
  35.     // destructor:        deletes storeStream & mutex
  36.                         ~IAStorage();
  37.  
  38.     // Initializes a new storage, or empties an existing one.
  39.     // The storage is left open afterwards.
  40.     virtual void        Initialize() = 0;
  41.  
  42.     // Opens the storage (and its storeStream), enabling subsequent operations.
  43.     // If `writable' is true, destructive operations are supported.
  44.     virtual void        Open(bool writable = false) = 0;
  45.     bool                IsOpen() { return storeStream->IsOpen(); }
  46.     bool                IsWritable() { return storeStream->IsWritable(); }
  47.                 
  48.     // Makes permanent any changes since open.
  49.     virtual void        Commit() = 0;
  50.  
  51.     // Allocates a new block.
  52.     virtual IABlockID    Allocate() = 0;
  53.     
  54.     // Frees a previously allocated block.
  55.     virtual void        Deallocate(IABlockID id) = 0;
  56.     
  57.     // The TOC (table of contents) maintains a list of named block IDs.
  58.     // This enables clients to find their data structures, which may have
  59.     // different block IDs in different storages.
  60.     virtual void        TOC_Set(const char* label, IABlockID id) = 0;
  61.     virtual IABlockID    TOC_Get(const char* label) = 0;
  62.     virtual    bool        TOC_Remove(const char* label) = 0;
  63.     /// Convenient functions capturing common TOC idioms:
  64.     // Adds a new TOC entry whose value is a newly allocated block ID.
  65.     IABlockID            AllocateNamedBlock(const char* name);
  66.     // If an entry already exists, returns it, otherwise calls AllocateNamedBlock().
  67.     IABlockID            GetNamedBlock(const char* name);
  68.     // If an entry exists, remove it.
  69.     bool                RemoveNamedBlock(const char* name);
  70.  
  71.     // The total number of bytes in the storage and free, respectively.
  72.     virtual IABlockSize    TotalSpace() = 0;
  73.     virtual IABlockSize    FreeSpace() = 0;
  74.     
  75.     // Attempts to compact the storage
  76.     virtual void        Compact() = 0;
  77.  
  78.     // in the debug libraries, prints some info about the set to the standard output
  79.     virtual void        PrintFreeList();
  80.     IAStoreStream*        GetStoreStream() const {return storeStream;}
  81.     const uint32        GetStorageType() const {return storageType;}
  82.     IAMutex*            GetMutex() const {return mutex;}
  83.  
  84. protected:
  85.     /// The following called only by InputBlock & OutputBlock (our friends).
  86.     /// Clients should always access block contents through InputBlock & OutputBlock.
  87.     
  88.     // Returns the address that a block may be read from.
  89.     virtual IABlockAddress    GetReadAddress(IABlockID id) = 0;
  90.     
  91.     // Returns the address that a block may be written to.
  92.     virtual IABlockAddress    GetWriteAddress(IABlockID id, IABlockSize size) = 0;
  93.  
  94.     // Returns the number of bytes currently allocated for a block.
  95.     virtual IABlockSize        GetBlockSize(IABlockID id) = 0;
  96.  
  97.     //// Give subclasses direct access to IAStoreStreams.
  98.     void    InitializeSS(IAStoreStream* s)                    { s->Initialize(); }
  99.     void    OpenSS(IAStoreStream* s, bool writeable)        { s->Open(writeable); }
  100.     void    FlushSS(IAStoreStream* s)                        { s->Flush(); }
  101.     uint32    GetEOF(IAStoreStream* s)                        { return s->GetEOF(); }
  102.     void    SetEOF(IAStoreStream* s, uint32 address)        { s->SetEOF(address); }
  103.     void    Write(IAStoreStream* s, uint32 a, const byte* d, uint32 l) { s->Write(a,d,l); }
  104.     uint32    Read(IAStoreStream* s, uint32 a, byte* d,  uint32 l) { return s->Read(a,d,l); }
  105.     uint32    GetPosition(IAStoreStream* s)                    { return s->GetPosition(); }
  106.     void    SetPosition(IAStoreStream* s, uint32 a, uint32 b) { s->SetPosition(a, b); }
  107.     void    WriteByte(IAStoreStream* s, byte b)             { s->WriteByte(b); }
  108.     byte    ReadByte(IAStoreStream* s)                        { return s->ReadByte(); }
  109.     void    WriteUInt32(IAStoreStream* s, uint32 i)         { s->WriteUInt32(i); }
  110.     uint32    ReadUInt32(IAStoreStream* s)                    { return s->ReadUInt32(); }
  111.     void    WriteBytes(IAStoreStream* s, const void* b, uint32 l) { s->WriteBytes(b,l); }
  112.     void    ReadBytes(IAStoreStream* s, void* b,  uint32 l)    { s->ReadBytes(b,l); }
  113.     IAMutex* SSMutex(IAStoreStream* s)                        { return s->mutex; }
  114. private:
  115.                         IAStorage(IAStorage&);    // don't define a copy constructor
  116.     IAStoreStream*        storeStream;            // used for raw i/o
  117.     const uint32        storageType;            // identifies the format used by this storage
  118.     IAMutex*            mutex;                    // to synchronize access
  119. };
  120.  
  121. // This should be used instead of a constructor to make a default-format storage.
  122. IAStorage*        IAMakeStorage(IAStoreStream* storeStream);
  123.  
  124.  
  125. // This class is allocated on the stack, as follows:
  126. //        IAOutputBlock    output(storage, blockID, size);
  127. class IAOutputBlock {
  128. public:
  129.     // locks stream's mutex & positions stream at address for write
  130.     // a cloned IAStoreStream can be supplied to improved threaded throughput
  131.     IAOutputBlock(IAStorage* sto, IABlockID id, IABlockSize sz, IAStoreStream* stream = NULL);
  132.     // flushes changes & unlocks stream's mutex
  133.     ~IAOutputBlock();
  134.  
  135.     void                WriteByte(byte b)                    { stream->WriteByte(b); }
  136.     void                WriteUInt32(uint32 i)                 { stream->WriteUInt32(i); }
  137.     void                WriteBuffer(const void* b, uint32 l){ stream->WriteBytes(b, l); }
  138.  
  139.     uint32                GetPosition()                     { return stream->GetPosition(); }
  140. private:
  141.     IAStoreStream*        stream;
  142.  
  143.     void*                operator new(size_t size);        // stack allocate only
  144.                         IAOutputBlock(IAOutputBlock&);    // don't define copy constructor
  145. };
  146.  
  147. // This class is allocated on the stack, as follows:
  148. //        IAInputBlock    input(storage, blockID);
  149. class IAInputBlock {
  150. public:
  151.     // locks stream's mutex & positions stream at address for read
  152.     // a cloned IAStoreStream can be supplied to improved threaded throughput
  153.     IAInputBlock(IAStorage* sto, IABlockID id, IAStoreStream* stream = NULL);
  154.     // unlocks stream's mutex
  155.     ~IAInputBlock();
  156.  
  157.     byte                ReadByte()                         { return stream->ReadByte(); }
  158.     uint32                ReadUInt32()                    { return stream->ReadUInt32(); }
  159.     void                ReadBuffer(void* b,  uint32 l)    { stream->ReadBytes(b, l); }
  160.  
  161.     uint32                GetPosition()                     { return stream->GetPosition(); }
  162. private:
  163.     IAStoreStream*        stream;
  164.  
  165.     void*                operator new(size_t size);        // stack allocate only
  166.                         IAInputBlock(IAInputBlock&);    // don't define copy constructor
  167. };
  168.  
  169.  
  170. IAExceptionCode                StorageInvalid = 'VSIV';
  171. IAExceptionCode                StorageNotInitialized = 'VSNI';
  172. IAExceptionCode                StorageNotOpen = 'VSNO';
  173. IAExceptionCode                StorageAlreadyOpen = 'VSAO';
  174.  
  175. IAExceptionCode                StorageFull = 'VSDF';
  176. IAExceptionCode                StorageNotWritable = 'VSNW';
  177. IAExceptionCode                StorageBlockIDInvalid = 'VSBI';
  178. IAExceptionCode                StorageBlockNameAllocated = 'VSNT';
  179.  
  180. #pragma IA_END_EXPORTS
  181.  
  182. #pragma import reset
  183. #endif
  184.